RtWaitForMultipleObjects

RtWaitForMultipleObjects allows a thread to wait on one of multiple objects to be signaled.

Syntax

DWORD RtWaitForMultipleObjects(
    DWORD nCount,
    CONST HANDLE *lpHandles,
    BOOL fWaitAll,
    DWORD dwMilliseconds
);

Parameters

nCount

Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAX_WFMO, as defined in RTAPI.h.

lpHandles

Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles to objects of different types. It may not contain the multiple copies of the same handle.

If one of these handles is closed while the wait is still pending, the function's behavior is undefined.

The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. The function returns when the state of any one of the objects set to is signaled. The return value indicates the object whose state caused the function to return.

RTSS Environment: This parameter must be FALSE, indicating WAIT FOR ANY.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the condition specified by the fWaitAll parameter are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

Return Values

The event that caused the function to return if the function succeeds

Possible return values are shown in this table:

Return Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount - 1)	The return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signalled during the call, this is the array index of the signalled object with the smallest index value of all the signalled objects.
WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount - 1)	The return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.
WAIT_TIMEOUT	The time-out interval elapsed and the conditions specified by the fWaitAll parameter are not satisfied. If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

Remarks

IMPORTANT! RtWaitForMultipleObjects cannot be used to wait on a RTX thread handle within a Windows program.

RtWaitForMultipleObjects determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters the wait state. It uses no processor time while waiting for the criteria to be met.

The function returns when one of these events occurs:

Any one of the specified object is in the signaled state
The time-out interval elapses

The function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one. When fWaitAll is FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the other objects are unaffected.

RtWaitForMultipleObjects can specify handles of any of the following object types in the lpHandles array:

Event
Mutex
Process
Semaphore
Thread

Requirements

Header	Rtapi.h
Library	rtapi_w32.lib (Windows), Rtx_Rtss.lib (RTSS)